home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dcopclient.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-10-08  |  28.3 KB  |  841 lines
  1. /*
  2. Copyright (c) 1999 Preston Brown <pbrown@kde.org>
  3. Copyright (c) 1999, 2000 Matthias Ettrich <ettrich@kde.org>
  4.  
  5. Permission is hereby granted, free of charge, to any person obtaining a copy
  6. of this software and associated documentation files (the "Software"), to deal
  7. in the Software without restriction, including without limitation the rights
  8. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9. copies of the Software, and to permit persons to whom the Software is
  10. furnished to do so, subject to the following conditions:
  11.  
  12. The above copyright notice and this permission notice shall be included in
  13. all copies or substantial portions of the Software.
  14.  
  15. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  18. AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  19. AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20. CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21. */
  22.  
  23. #ifndef _DCOPCLIENT_H
  24. #define _DCOPCLIENT_H
  25.  
  26. #include <qobject.h>
  27. #include <qcstring.h>
  28. #include <qvaluelist.h>
  29. #include <qstring.h>
  30. #include <kdatastream.h> // needed for proper bool marshalling
  31. #include <kdelibs_export.h>
  32.  
  33. class DCOPObjectProxy;
  34. class DCOPClientPrivate;
  35. class DCOPClientTransaction;
  36.  
  37. typedef QValueList<QCString> QCStringList;
  38.  
  39. /**
  40.  * Inter-process communication and remote procedure calls
  41.  * for KDE applications.
  42.  *
  43.  * This class provides IPC and RPC for KDE applications.  Usually you
  44.  * will not have to instantiate one yourself because KApplication
  45.  * contains a method to return a pointer to a DCOPClient object which
  46.  * can be used for your whole application.
  47.  *
  48.  * Before being able to send or receive any DCOP messages, you will have
  49.  * to attach your client object to the DCOP server, and then register
  50.  * your application with a specific name. See attach()
  51.  * and registerAs() for
  52.  * more information.
  53.  *
  54.  * Data to be sent should be serialized into a QDataStream which was
  55.  * initialized with the QByteArray that you actually intend to send
  56.  * the data in.  An example of how you might do this:
  57.  *
  58.  * \code
  59.  *   QByteArray data;
  60.  *   QDataStream arg(data, IO_WriteOnly);
  61.  *   arg << QString("This is text I am serializing");
  62.  *   client->send("someApp", "someObject", "someFunction(QString)", data);
  63.  * \endcode
  64.  *
  65.  * @see KApplication::dcopClient()
  66.  * @author Preston Brown <pbrown@kde.org>, Matthias Ettrich <ettrich@kde.org>
  67.  */
  68. class DCOP_EXPORT DCOPClient : public QObject
  69. {
  70.   Q_OBJECT
  71.  
  72.  public:
  73.   /**
  74.    * Constructs a new DCOP client, but does not attach to any server.  */
  75.   DCOPClient();
  76.  
  77.   /**
  78.    * Cleans up any open connections and dynamic data.
  79.    */
  80.   virtual ~DCOPClient();
  81.  
  82.   /**
  83.    * Sets the address of a server to use upon attaching.
  84.    *
  85.    * If no server address is ever specified, attach will try its best to
  86.    * find the server anyway.
  87.    * @param addr the new address of the server
  88.    */
  89.   static void setServerAddress(const QCString &addr);
  90.  
  91.   /**
  92.    * Attaches to the DCOP server.
  93.    *
  94.    * If the connection was already attached,
  95.    * the connection will be re-established with the current server address.
  96.    *
  97.    * Naturally, only attached application can use DCOP services.
  98.    *
  99.    * If a QApplication object exists then client registers itself as
  100.    * QApplication::name() + "-" + \<pid\>.
  101.    * If no QApplication object exists the client registers itself as
  102.    * "anonymous".
  103.    *
  104.    * If you want to register differently, you should use registerAs()
  105.    * instead.
  106.    *
  107.    * @return true if attaching was successful.
  108.    */
  109.   bool attach();
  110.  
  111.   /**
  112.    * @internal
  113.    * Internal function for KUniqueApplication to register the DCOPClient
  114.    * with the application in case the application didn't exist at the
  115.    * time the DCOPClient was created.
  116.    */
  117.   void bindToApp();
  118.  
  119.   /**
  120.    * Detaches from the DCOP server.
  121.    * @return true if successful, false otherwise
  122.    */
  123.   bool detach();
  124.  
  125.   /**
  126.    * Returns whether or not the client is attached to the server.
  127.    * @return true if attached, false if not
  128.    */
  129.   bool isAttached() const;
  130.  
  131.   /**
  132.    * Returns whether the client is attached to a server owned by
  133.    * another user.
  134.    * @return true if attached to a foreign server, false if not
  135.    */
  136.   bool isAttachedToForeignServer() const;
  137.  
  138.   /**
  139.    * Returns whether the client handles incoming calls.
  140.    * @return true if the client accepts calls
  141.    */
  142.   bool acceptCalls() const;
  143.  
  144.   /**
  145.    * Specify whether the client should accept incoming calls.
  146.    * By default clients accept incoming calls, but not when connected
  147.    * to a foreign server.
  148.    * @param b true to accept calls, false to reject them
  149.    */
  150.   void setAcceptCalls(bool b);
  151.  
  152.   /**
  153.    * Returns whether the DCOP - Qt bridge is enabled.
  154.    * By default the DCOP - Qt bridge is enabled.
  155.    * @return true if Qt objects are accessible over DCOP
  156.    * @since 3.0.2
  157.    */
  158.   bool qtBridgeEnabled(); // ### KDE 4.0: make const
  159.  
  160.   /**
  161.    * Specify whether Qt objects of the application should be accessible
  162.    * via DCOP.
  163.    * By default the DCOP - Qt bridge is enabled.
  164.    * @param b true to make Qt objects accessible over DCOP
  165.    * @since 3.0.2
  166.    */
  167.   void setQtBridgeEnabled(bool b);
  168.  
  169.   /**
  170.    * Registers at the DCOP server.
  171.    *
  172.    * If the application was already registered,
  173.    * the registration will be re-done with the new appId.
  174.    *
  175.    * @p appId is a @p unique application/program id that the server
  176.    * will use to associate requests with. If there is already an application
  177.    * registered with the same name, the server will add a number to the
  178.    * id to unify it. If @p addPID is true, the PID of the current process
  179.    * will be added to id.
  180.    *
  181.    * Registration is necessary if you want to allow other clients to talk
  182.    * to you.  They can do so using your @p appId as first parameter
  183.    * for send() or call(). If you just want to talk to
  184.    *  other clients, you
  185.    * do not need to register at the server. In that case attach() is
  186.    * enough.
  187.    * It will implicitly register you as "anonymous".
  188.    *
  189.    * @param appId the id of the application
  190.    * @param addPID true to add the process id
  191.    * @return The actual @p appId used for the registration or a null string
  192.    * if the registration wasn't successful.
  193.    */
  194.   QCString registerAs( const QCString &appId, bool addPID = true );
  195.  
  196.   /**
  197.    * Returns whether or not the client is registered at the server.
  198.    * @return true if registered at the server
  199.    */
  200.   bool isRegistered() const;
  201.  
  202.   /**
  203.    * Returns the current app id or a null string if the application
  204.    * hasn't yet been registered.
  205.    * @return the application id, or QString::null if not registered
  206.    */
  207.   QCString appId() const;
  208.  
  209.   /**
  210.    * Returns the socket fd that is used for communication with the server.
  211.    * @return The socket over which DCOP is communicating with the server.
  212.    */
  213.   int socket() const;
  214.  
  215.   /**
  216.    * Temporarily suspends processing of DCOP events.
  217.    * This can be useful if you need to show e.g. a dialog before
  218.    * your application is ready to accept DCOP requests. Normally the
  219.    * dialog would start an event loop and in this event loop DCOP
  220.    * requests will be handled.
  221.    *
  222.    * Be aware that not responding to DCOP requests may cause other
  223.    * programs that want to communicate with your application, to hang.
  224.    * @see resume()
  225.    * @see isSuspended()
  226.    */
  227.   void suspend();
  228.  
  229.   /**
  230.    * Resumes the processing of DCOP events.
  231.    * @see suspend().
  232.    * @see isSuspended()
  233.    */
  234.   void resume();
  235.  
  236.   /**
  237.    * Returns whether DCOP events are being processed.
  238.    * @see suspend()
  239.    * @see resume().
  240.    * @since 3.1
  241.    */
  242.   bool isSuspended() const;
  243.  
  244.   /**
  245.    * Sends a data block to the server.
  246.    *
  247.    * @param remApp The remote application id.
  248.    * @param remObj The name of the remote object.
  249.    * @param remFun The remote function in the specified object to call.
  250.    * @param data The data to provide to the remote function.
  251.    *
  252.    * @return Whether or not the server was able to accept the send.
  253.    */
  254.   bool send(const QCString &remApp, const QCString &remObj,
  255.         const QCString &remFun, const QByteArray &data);
  256.  
  257.   /**
  258.    * This function acts exactly the same as the above, but the data
  259.    * parameter can be specified as a QString for convenience.
  260.    *
  261.    * @param remApp The remote application id.
  262.    * @param remObj The name of the remote object.
  263.    * @param remFun The remote function in the specified object to call.
  264.    * @param data The data to provide to the remote function.
  265.    *
  266.    * @return Whether or not the server was able to accept the send.
  267.    */
  268.   bool send(const QCString &remApp, const QCString &remObj,
  269.         const QCString &remFun, const QString &data);
  270.  
  271.   /**
  272.    * Performs a synchronous send and receive.
  273.    *
  274.    *  The parameters are the same as for send, with the exception of
  275.    *  another QByteArray being provided for results to be
  276.    *  (optionally) returned in.
  277.    *
  278.    * A call blocks the application until the process receives the
  279.    * answer.
  280.    *
  281.    * If @p useEventLoop is true, a local event loop will be started after
  282.    * 1/10th of a second in order to keep the user interface updated
  283.    * (by processing paint events and such) until an answer is received.
  284.    *
  285.    * @param remApp the remote application's id
  286.    * @param remObj the remote object id
  287.    * @param remFun the remote function id
  288.    * @param data the data to send
  289.    * @param replyType the type of the reply will be written here
  290.    * @param replyData the data of the reply will be written here
  291.    * @param useEventLoop if true the event loop will be started when
  292.    *         the call blocks too long
  293.    * @param timeout timeout for the call in miliseconds, or -1 for no timeout
  294.    * @return true if successful, false otherwise
  295.    *
  296.    * @since 3.2
  297.    *
  298.    * @see send()
  299.    */
  300.   bool call(const QCString &remApp, const QCString &remObj,
  301.         const QCString &remFun, const QByteArray &data,
  302.         QCString& replyType, QByteArray &replyData,
  303.         bool useEventLoop/*=false*/, int timeout/*=-1*/);
  304.   /**
  305.    * @deprecated
  306.    */
  307.   // KDE4 merge with above
  308.   bool call(const QCString &remApp, const QCString &remObj,
  309.         const QCString &remFun, const QByteArray &data,
  310.         QCString& replyType, QByteArray &replyData,
  311.         bool useEventLoop=false);
  312.  
  313.   /**
  314.    * Performs a asynchronous send with receive callback.
  315.    *
  316.    *  The first four parameters are the same as for send.
  317.    *
  318.    * @p callBackObj and @p callBackSlot specify a call back
  319.    * slot that is called when an answer is received.
  320.    *
  321.    * The slot should have the following signature:
  322.    * callBackSlot(int callId, const QCString& replyType,
  323.    *              const QByteArray &replyData);
  324.    *
  325.    *
  326.    * @param remApp the remote application's id
  327.    * @param remObj the remote object id
  328.    * @param remFun the remote function id
  329.    * @param data the data to send
  330.    * @param callBackObj object to call back
  331.    * @param callBackSlot slot to call back
  332.    * @return 0 on failure, on success a callId > 0 is
  333.    * returned that will be passed as first argument of
  334.    * the result call back
  335.    *
  336.    * @see send()
  337.    * @see callback()
  338.    *
  339.    * @since 3.2
  340.    */
  341.   int callAsync(const QCString &remApp, const QCString &remObj,
  342.                 const QCString &remFun, const QByteArray &data,
  343.                 QObject *callBackObj, const char *callBackSlot);
  344.  
  345.   /**
  346.    * Searches for an object which matches a criteria.
  347.    *
  348.    * findObject calls @p remFun in the applications and objects identified
  349.    * by @p remApp and @p remObj until @p remFun returns true. The name of
  350.    * the application and object that returned true are returned in
  351.    * @p foundApp and @p foundObj respectively.
  352.    *
  353.    * If @p remFun is empty a default function is called in the object
  354.    * which always returns @p true.
  355.    *
  356.    * A findObject blocks the application until the process receives the
  357.    * answer.
  358.    *
  359.    * If @p useEventLoop is true, a local event loop will be started after
  360.    * 1/10th of a second in order to keep the user interface updated
  361.    * (by processing paint events and such) until an answer is received.
  362.    *
  363.    * @param remApp The remote application id.
  364.    * @param remObj The name of the remote object.
  365.    * @param remFun The remote function in the specified object to call.
  366.    *               This function should return a bool and is used as
  367.    *               criteria.
  368.    * @param data The data to provide to the remote function.
  369.    * @param foundApp The remote application id that matched the criteria.
  370.    * @param foundObj The remote object that matched the criteria.
  371.    * @param useEventLoop if true the event loop will be started when
  372.    *         the call blocks too long
  373.    * @param timeout timeout for the call in miliseconds, or -1 for no timeout
  374.    * @return true is returned when an object was found for which @p remFun
  375.    *         returned true. If no such object is the function returns false.
  376.    *
  377.    * @since 3.2
  378.    *
  379.    * @see send()
  380.    */
  381.   bool findObject(const QCString &remApp, const QCString &remObj,
  382.         const QCString &remFun, const QByteArray &data,
  383.         QCString &foundApp, QCString &foundObj,
  384.         bool useEventLoop/*=false*/, int timeout/*=-1*/);
  385.  
  386.   /**
  387.    * @deprecated
  388.    */
  389.   // KDE4 merge with above
  390.   bool findObject(const QCString &remApp, const QCString &remObj,
  391.         const QCString &remFun, const QByteArray &data,
  392.         QCString &foundApp, QCString &foundObj,
  393.         bool useEventLoop=false);
  394.  
  395.  
  396.   /**
  397.    * Emits @p signal as DCOP signal from object @p object with @p data as
  398.    * arguments.
  399.    */
  400.   void emitDCOPSignal( const QCString &object, const QCString &signal,
  401.                        const QByteArray &data);
  402.  
  403.   /* For backwards compatibility */
  404.   void emitDCOPSignal( const QCString &signal, const QByteArray &data);
  405.  
  406.   /**
  407.    * Connects to a DCOP signal.
  408.    * @param sender the name of the client that emits the signal. When empty
  409.    * the signal will be passed from any client.
  410.    * @param senderObj the name of the sending object that emits the signal.
  411.    * @param signal the name of the signal. The arguments should match with slot.
  412.    * @param receiverObj The name of the object to call
  413.    * @param slot The name of the slot to call. Its arguments should match with signal.
  414.    * @param Volatile If true, the connection will not be reestablished when
  415.    * @p sender unregisters and reregisters with DCOP. In this case the @p sender
  416.    * must be registered when the connection is made.
  417.    * If false, the connection will be reestablished when @p sender reregisters.
  418.    * In this case the connection can be made even if @p sender is not registered
  419.    * at that time.
  420.    *
  421.    * @return false if a connection could not be established.
  422.    * This will be the case when
  423.    * @li @p Volatile is true and @p sender  does not exist.
  424.    * @li @p signal and @p slot do not have matching arguments.
  425.    */
  426.   bool connectDCOPSignal( const QCString &sender, const QCString &senderObj,
  427.                           const QCString &signal,
  428.                           const QCString &receiverObj, const QCString &slot,
  429.                           bool Volatile);
  430.  
  431.   /**
  432.    * @deprecated
  433.    * For backwards compatibility
  434.    */
  435.   bool connectDCOPSignal( const QCString &sender, const QCString &signal,
  436.                           const QCString &receiverObj, const QCString &slot,
  437.                           bool Volatile) KDE_DEPRECATED;
  438.  
  439.   /**
  440.    * Disconnects a DCOP signal.
  441.    *
  442.    * A special case is when both @p sender & @p signal are empty. In this
  443.    * case all connections related to @p receiverObj in the current client
  444.    * are disconnected. (Both connections from as well as to this object!)
  445.    *
  446.    * @param sender the name of the client that emits the signal.
  447.    * @param senderObj the name of the object that emits the signal.
  448.    * If empty all objects will be disconnected.
  449.    * @param signal the name of the signal. The arguments should match with slot.
  450.    * @param receiverObj The name of the object the signal is connected to.
  451.    * If empty all objects will be disconnected.
  452.    * @param slot The name of the slot the signal is connected to.
  453.    * If empty all slots will be disconnected.
  454.    * @return false if no connection(s) where removed.
  455.    */
  456.   bool disconnectDCOPSignal( const QCString &sender, const QCString &senderObj,
  457.                           const QCString &signal,
  458.                           const QCString &receiverObj, const QCString &slot);
  459.  
  460.   /**
  461.    * @deprecated
  462.    * For backwards compatibility
  463.    */
  464.   bool disconnectDCOPSignal( const QCString &sender, const QCString &signal,
  465.                           const QCString &receiverObj, const QCString &slot) KDE_DEPRECATED;
  466.  
  467.   /**
  468.    * Reimplement this function to handle app-wide function calls unassociated w/an object.
  469.    *
  470.    * Note that @p fun is normalized. See normalizeFunctionSignature().
  471.    *
  472.    * If you do not want to reimplement this function for whatever reason,
  473.    * you can also use a default object  or a DCOPObjectProxy.
  474.    *
  475.    * @param fun the normalized function signature
  476.    * @param data the received data
  477.    * @param replyType write the reply type in this string
  478.    * @param replyData write the reply data in this array
  479.    * @return true if successful, false otherwise
  480.    * @see setDefaultObject()
  481.    */
  482.   virtual bool process(const QCString &fun, const QByteArray &data,
  483.                QCString& replyType, QByteArray &replyData);
  484.  
  485.   /**
  486.    * Delays the reply of the current function call
  487.    * until endTransaction() is called.
  488.    *
  489.    * This allows a server to queue requests.
  490.    *
  491.    * Note: Should be called from inside process() only!
  492.    * @see endTransaction()
  493.    */
  494.   DCOPClientTransaction *beginTransaction( );
  495.  
  496.   /**
  497.    * Sends the delayed reply of a function call.
  498.    * @param t the transaction as received from beginTransaction()
  499.    * @param replyType write the reply type in this string
  500.    * @param replyData write the reply data in this array
  501.    * @see beginTransaction()
  502.    */
  503.   void endTransaction( DCOPClientTransaction *t, QCString& replyType, QByteArray &replyData);
  504.  
  505.   /**
  506.    * Test whether the current function call is delayed.
  507.    *
  508.    * Note: Should be called from inside process() only!
  509.    * @return The ID of the current transaction or
  510.    *         0 if no transaction is going on.
  511.    * @see process()
  512.    * @see beginTransaction()
  513.    */
  514.   Q_INT32 transactionId() const;
  515.  
  516.   /**
  517.    * Checks whether @p remApp is registered with the DCOP server.
  518.    * @param remApp the id of the remote application
  519.    * @return true if the remote application is registered, otherwise @p false.
  520.    */
  521.   bool isApplicationRegistered( const QCString& remApp);
  522.  
  523.   /**
  524.    * Retrieves the list of all currently registered applications
  525.    * from dcopserver.
  526.    * @return a list of all regietered applications
  527.    */
  528.   QCStringList registeredApplications();
  529.  
  530.   /**
  531.    * Retrieves the list of objects of the remote application @p remApp.
  532.    * @param remApp he id of the application
  533.    * @param ok if not null, the function sets @p ok to true if successful
  534.    *           and false if an error occurred
  535.    * @return the list of object ids
  536.    */
  537.   QCStringList remoteObjects( const QCString& remApp, bool *ok = 0 );
  538.  
  539.   /**
  540.    * Retrieves the list of interfaces of the remote object @p remObj
  541.    * of application @p remApp.
  542.    * @param remApp the id of the application
  543.    * @param remObj the id of the object
  544.    * @param ok if not null, the function sets @p ok to true if successful
  545.    *           and false if an error occurred
  546.    * @return the list of interfaces
  547.   */
  548.   QCStringList remoteInterfaces( const QCString& remApp, const QCString& remObj , bool *ok = 0 );
  549.  
  550.   /**
  551.    * Retrieves the list of functions of the remote object @p remObj
  552.    * of application @p remApp
  553.    * @param remApp the id of the application
  554.    * @param remObj the id of the object
  555.    * @param ok if not null, the function sets @p ok to true if successful
  556.    *           and false if an error occurred
  557.    * @return the list of function ids
  558.   */
  559.   QCStringList remoteFunctions( const QCString& remApp, const QCString& remObj , bool *ok = 0 );
  560.  
  561.   /**
  562.    * @internal
  563.    * Receives a DCOPSend or DCOPCall message from the server.
  564.    *
  565.    * @param app The application the message was intended for.  Should be
  566.    *        equal to our appId that we passed when the DCOPClient was
  567.    *        created.
  568.    * @param obj The name of the object to pass the data on to.
  569.    * @param fun The name of the function in the object to call.
  570.    * @param data The arguments for the function.
  571.    * @param replyType write the reply type in this string
  572.    * @param replyData write the reply data in this array
  573.    * @return true if successful, false otherwise
  574.    */
  575.   bool receive(const QCString &app, const QCString &obj,
  576.            const QCString &fun, const QByteArray& data,
  577.            QCString& replyType, QByteArray &replyData);
  578.  
  579.   /**
  580.    * @internal
  581.    * Receives a @p DCOPFind message from the server.
  582.    *
  583.    * @param app The application the message was intended for.  Should be
  584.    *        equal to our appId that we passed when the DCOPClient was
  585.    *        created.
  586.    * @param obj The name of the object to pass the data on to.
  587.    * @param fun The name of the function in the object to call.
  588.    * @param data The arguments for the function.
  589.    * @param replyType write the reply type in this string
  590.    * @param replyData write the reply data in this array
  591.    */
  592.   bool find(const QCString &app, const QCString &obj,
  593.         const QCString &fun, const QByteArray& data,
  594.         QCString& replyType, QByteArray &replyData);
  595.  
  596.   /**
  597.    * Normalizes the function signature @p fun.
  598.    *
  599.    * A normalized signature doesn't contain any unnecessary whitespace
  600.    * anymore. The remaining whitespace consists of single blanks only (0x20).
  601.    *
  602.    * Example for a normalized signature:
  603.    * \code
  604.    *   "someFunction(QString,int)"
  605.    * \endcode
  606.    *
  607.    * When using send() or call(), normalization is done
  608.    * automatically for you.
  609.    *
  610.    * @param fun the function signature to normalize
  611.    * @return the normalized function
  612.    */
  613.   static QCString normalizeFunctionSignature( const QCString& fun );
  614.  
  615.  
  616.   /**
  617.    * Returns the appId of the last application that talked to us.
  618.    * @return the application id of the last application that send a message
  619.    *         to this client
  620.    */
  621.   QCString senderId() const;
  622.  
  623.  
  624.    /**
  625.     * Installs object @p objId as application-wide default object.
  626.     *
  627.     * All app-wide messages that have not been processed by the dcopclient
  628.     * will be send further to @p objId.
  629.     * @param objId the id of the new default object
  630.     */
  631.   void setDefaultObject( const QCString& objId );
  632.  
  633.     /**
  634.      * Returns the current default object or an empty string if no object is
  635.      * installed as default object.
  636.      *
  637.      * A default object receives application-wide messages that have not
  638.      * been processed by the DCOPClient itself.
  639.     * @return the id of the new default object
  640.      */
  641.   QCString defaultObject() const;
  642.  
  643.   /**
  644.    * Enables / disables the applicationRegistered() /
  645.    * applicationRemoved() signals.
  646.    * Note that a counter is maintained about how often this method
  647.    * was called. If this method is called twice with @p enabled set to
  648.    * true, notifications will be enabled until it was called with
  649.    * @p enabled set to false as often.
  650.    *
  651.    * They are disabled by default.
  652.    * @param enabled true to enable notifications, false to disable
  653.    */
  654.   void setNotifications( bool enabled );
  655.  
  656.   /**
  657.    * Tells the dcopserver to treat the client as daemon client, not
  658.    * as regular client.
  659.    * If the number of regular clients drops down to zero, the
  660.    * dcopserver will emit a KDE termination signal after 10
  661.    * seconds.
  662.    * @param daemonMode true to enable daemon mode, false to disable
  663.    */
  664.   void setDaemonMode( bool daemonMode );
  665.  
  666.   /**
  667.    * @internal
  668.    *
  669.    * Switch to priority call mode.
  670.    */
  671.   void setPriorityCall(bool);
  672.  
  673.   /**
  674.    * Returns the application's main dcop client. The main client can
  675.    * be used by objects that do not have any specific access to a dcop
  676.    * client. In KDE applications, the main client usually is the same
  677.    * as KApplication::dcopClient().
  678.    * @return the application's main dcop client
  679.    */
  680.   static DCOPClient* mainClient();
  681.  
  682.  /**
  683.    * Sets the application's main dcop client. The main client can
  684.    * be used by objects that do not have any specific access to a dcop
  685.    * client. In KDE applications, the main client usually is the same
  686.    * as KApplication::dcopClient().
  687.    * @param mainClient the new main dcop client
  688.    */
  689.   static void setMainClient( DCOPClient* mainClient);
  690.  
  691.   /**
  692.    * Look for the given client only in this process. This can be used
  693.    * to check whether a given client (by name) is running in the same
  694.    * process or in another one.
  695.    */
  696.   static DCOPClient* findLocalClient( const QCString &_appId );
  697.  
  698.   /**
  699.     * @internal Do not use.
  700.     */
  701.   static void emergencyClose();
  702.  
  703.   /**
  704.     * @internal Do not use.
  705.     *
  706.     * Provides information about the last DCOP call for debugging purposes.
  707.     */
  708.   static const char *postMortemSender();
  709.   /** @internal */
  710.   static const char *postMortemObject();
  711.   /** @internal */
  712.   static const char *postMortemFunction();
  713.  
  714.   /**
  715.     * File with information how to reach the dcopserver.
  716.     * @param hostname Hostname to use, if empty current hostname of
  717.     * the system is used.
  718.     * @return Filename that contains information how to contact the
  719.     * DCOPserver.
  720.     */
  721.   static QCString dcopServerFile(const QCString &hostname=0);
  722.  
  723.   /**
  724.    * @deprecated
  725.    * For backwards compatibility with KDE 2.x
  726.    * // KDE4 remove
  727.    */
  728.   static QCString dcopServerFileOld(const QCString &hostname=0) KDE_DEPRECATED;
  729.  
  730.   /**
  731.    * Return the path of iceauth or an empty string if not found.
  732.    */
  733.   static QCString iceauthPath();
  734.  
  735. signals:
  736.   /**
  737.    * Indicates that the application @p appId has been registered with
  738.    * the server we are attached to.
  739.    *
  740.    * You need to call setNotifications() first, to tell the DCOP server
  741.    * that you want to get these events.
  742.    * @param appId the id of the new application
  743.    */
  744.   void applicationRegistered( const QCString& appId );
  745.   /**
  746.    * Indicates that the formerly registered application @p appId has
  747.    * been removed.
  748.    *
  749.    * You need to call setNotifications() first, to tell the
  750.    * DCOP server that you want to get these events.
  751.    * @param appId the id of the removed application
  752.    */
  753.   void applicationRemoved( const QCString& appId );
  754.  
  755.   /**
  756.    * Indicates that the process of establishing DCOP communications failed
  757.    * in some manner.
  758.    *
  759.    *  Usually attached to a dialog box or some other visual
  760.    * aid.
  761.    * @param msg the message tha contains further information
  762.    */
  763.   void attachFailed(const QString &msg);
  764.  
  765.   /**
  766.    * Indicates that user input shall be blocked or released,
  767.    * depending on the argument.
  768.    *
  769.    * The signal is emitted whenever the client has to wait too long
  770.    * (i.e. more than 1/10 of a second) for an answer to a
  771.    * synchronous call. In that case, it will enter a local event
  772.    * loop to keep the GUI updated until finally an answer arrives.
  773.    *
  774.    * In KDE, the KApplication object connects to this signal to be
  775.    * able to block any user input (i.e. mouse and key events) while
  776.    * we are waiting for an answer. If we did not do this, the
  777.    * application might end up in an illegal state, as a keyboard
  778.    * shortcut or a mouse action might cause another dcop call to be
  779.    * issued.
  780.    * @param block true to block user input, false otherwise
  781.    */
  782.   void blockUserInput( bool block );
  783.  
  784.   /**
  785.    * @internal
  786.    *
  787.    * Signal used for callbacks of async calls.
  788.    * This signal is automatically connected to the call back
  789.    * slot specified in the async call.
  790.    * @see callAsync()
  791.    * @since 3.2
  792.    */
  793.   void callBack(int, const QCString&, const QByteArray &);
  794.  
  795. public slots:
  796.   /**
  797.    * Process data from the socket.
  798.    * @param socknum the fd of the socket
  799.    */
  800.   void processSocketData(int socknum);
  801.  
  802. protected slots:
  803.  
  804. private slots:
  805.   void processPostedMessagesInternal();
  806.   void asyncReplyReady();
  807.   void eventLoopTimeout();
  808.  
  809. public:
  810.   class ReplyStruct;
  811.  
  812.   /**
  813.    * @internal
  814.    **/
  815.   void handleAsyncReply(ReplyStruct *replyStruct);
  816.  
  817. private:
  818.  
  819.   bool isLocalTransactionFinished(Q_INT32 id, QCString &replyType, QByteArray &replyData);
  820.  
  821.   bool attachInternal( bool registerAsAnonymous = true );
  822.  
  823.   bool callInternal(const QCString &remApp, const QCString &remObj,
  824.         const QCString &remFun, const QByteArray &data,
  825.         QCString& replyType, QByteArray &replyData,
  826.         bool useEventLoop, int timeout, int minor_opcode);
  827.  
  828.  
  829.   bool callInternal(const QCString &remApp, const QCString &remObjId,
  830.             const QCString &remFun, const QByteArray &data,
  831.             ReplyStruct *replyStruct,
  832.             bool useEventLoop, int timeout, int minor_opcode);
  833.  
  834. protected:
  835.   virtual void virtual_hook( int id, void* data );
  836. private:
  837.   DCOPClientPrivate *d;
  838. };
  839.  
  840. #endif
  841.